Directly Manipulating a Shape's Geometry (IM: XO)

Inside Macintosh: QuickDraw GX Objects /: Chapter 2 - Shape Objects / Using Shape Objects

Directly Manipulating a Shape's Geometry
The geometry of a shape object is its most central property. Unlike other properties, it can be made accessible to you as a structure that you can modify directly, in place in QuickDraw GX memory. QuickDraw GX provides a group of functions with which you can access a shape's geometry and notify QuickDraw GX once you have modified it. Note that in most cases you don't need to do this; QuickDraw GX provides many functions, specific to each type of shape, with which you can access and modify geometry. The functions described here are provided as an added convenience.
These functions do not provide you with information about the formats of the data structures that make up shape geometries; they simply give you a pointer to the geometry. How you manipulate that information depends on the type of shape whose geometry you are accessing. The structures of individual shape geometries are described in the shape-specific chapters of Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography.
Before accessing a shape's geometry, you must set its gxDirectShape attribute to make sure that it is loaded into directly accessible memory. To access the geometry, you first call the GXLockShape function to make sure the shape object doesn't move until you are finished with it. You then call the GXGetShapeStructure function, which returns a pointer to the shape's geometry. You can then modify the geometry as needed. Once finished, you call GXUnlockShape to free the shape object for relocation in memory as needed. Finally, you must call GXChangedShape to notify QuickDraw GX that you have changed the geometry.
Listing 2-1 is a partial listing of a function that accesses the geometry of the path shape myShape, manipulating its geometry as a gxPaths structure in a buffer of size size.
Listing 2-1 Directly accessing a shape's geometry
.
. /* set up the shape (not shown) */
.
/* set the direct shape attribute if not set */
GXSetShapeAttributes (myShape, 
                  GXGetShapeAttributes(myShape) | gxDirectShape);

/* lock and examine or change the shape */
GXLockShape(myShape);
shapeStruct = (gxPaths*)GXGetShapeStructure(myShape, &size);
.
. /* unlock the shape as soon as access no longer needed */
.
GXUnlockShape(myShape);

/* notify QuickDraw GX of a change only if geometry changed */
GXChangedShape(myShape);
IMPORTANT
Memory-handling complications can occur with locked objects. Locking an object fragments the QuickDraw GX heap, which can result in lower performance. Furthermore, if a fragmented-memory condition occurs during a call, QuickDraw GX may unlock all objects and restart the call. Therefore, be careful about performing memory-intensive operations while there are locked objects in QuickDraw GX memory; they may become unlocked and be moved.
The GXLockShape function is described on page 2-80. The GXGetShapeStructure function is described on page 2-82. The GXUnlockShape function is described on page 2-81. The GXChangedShape function is described on page 2-83.